home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / c / hcsvga12.zip / HICOLOR.DOC < prev    next >
Text File  |  1993-05-24  |  19KB  |  661 lines
  1.  
  2.  
  3.               H C   S V G A
  4.  
  5.                Version 1.2b
  6.                May 20, 1993
  7.  
  8.      A Library for Tseng(tm) and VESA HiColor(tm) Graphics
  9.              and Turbo/Borland(tm) C
  10. Copyright 1990,1991,1993 Synergrafix Consulting.  All Rights Reserved
  11.  
  12.      HCSVGA is produced by:
  13.  
  14.            Steve Enns            Synergrafix Consulting 
  15.         44 Macdermid Cres.        - Custom Programming
  16.           Saskatoon, Sk.          - Graphical and Numerical Software
  17.           Canada S7J 2R2          - Hardware and Software Consultation
  18.  
  19.  
  20. ACKNOWLEDGEMENTS
  21.  
  22.      Thanks to all the contributors to the absolutely superb graphics
  23.      books:
  24.  
  25.     Graphics Gems    Academic Press, Edited by Andrew S. Glassner, 1990,
  26.             ISBN 0-12-286165-5
  27.  
  28.     Graphics Gems II  Academic Press, Edited by James Arvo, 1991,
  29.               ISBN 0-12-064480-0
  30.  
  31.      Thanks as well to some greatly inspirational and explicit code
  32.      by Michael Abrash in the November 1991 Doctor Dobbs Journal.
  33.  
  34.      Finally, great thanks to Daniel Lee Crocker and the Stone Soup
  35.      Group for numerous tremendous contributions to the public good
  36.      through PICLAB, and FRACTINT (the best program ever written) both
  37.      containing very enlightening Targa(tm) file code.
  38.  
  39.      Trademarks like GIF(tm) and PC(tm) are held by
  40.      their respective companies. 
  41.  
  42.  
  43. DISCLAIMER
  44.  
  45.      The HCSVGA library and associated files (the "package") is provided
  46.      without warranty of any kind.  The user of the HCSVGA package assumes
  47.      complete responsibility for any and all incidental or consequential
  48.      damages which may occur during normal or abnormal use of the
  49.      HCSVGA package.  Use the HCSVGA package at your own risk.
  50.  
  51.  
  52. LICENSE
  53.  
  54.      The entire HCSVGA package, including the HCSVGA library,
  55.      documentation, and sample files are Copyright 1990,1991,1992
  56.      Synergrafix Consulting.  All rights reserved.  The HCSVGA
  57.      package may be freely distributed to others by any means, as
  58.      long the following (three) conditions are met:
  59.  
  60.       1) HCSVGA is distributed in a "package" containing
  61.       all the files listed in the HCREAD.ME file.
  62.  
  63.       2) HCSVGA is not distributed as part of any other
  64.       product, except with specific written permission from
  65.       the authors.
  66.  
  67.       3) NO fee of any kind is charged for the HCSVGA
  68.       package or for the service of providing the package,
  69.       except Computer Bulletin Board Systems or Services,
  70.       which may distribute the HCSVGA package even though they
  71.       may charge a membership or service fee.
  72.  
  73.  
  74.      If you are seriously interested in the source code for this 
  75.      library, then write me a letter with your proposed uses for
  76.      the code, and I'll return a quote for the price.  (Probably
  77.      $50.00-$100.00 with no royalties.)
  78.  
  79.  
  80. REQUIREMENTS
  81.  
  82.       HCSVGA requires the following:
  83.  
  84.            -    PC(tm)/XT(tm)/AT(tm)/386(tm) computer
  85.            -    TSENG 4000 based Video Card equipped with
  86.             at least 1 Megabyte of display memory, and
  87.             a Sierra HiColor(tm) DAC chip, or an ATI XL
  88.             HiColor equipped card, or a VESA compliant
  89.             driver for you HiColor capable card.
  90.            -    A compatible C compiler (currently 
  91.             probably only works with Borland(tm))
  92.     
  93.  
  94. EXAMPLES
  95.  
  96.      See the following files for exmaple code using the library:
  97.  
  98.  
  99.     - HCTGAV.C    View TGA(tm) files on your HiColor card.
  100.         - HCGIFV.C    View GIF(tm) files...
  101.         - HCMOUSE.C    Interactive mouse demo.
  102.         - HCART.C    Draw HiColor patterns.
  103.     - MAKEDEMO.BAT  Compile the demo programs.
  104.  
  105.  
  106. HISTORY
  107.  
  108.      - Version 1.0b Completed December 20 1991
  109.     Just a Beta version!  Lots more to be done...
  110.  
  111.      - Version 1.2b Completed May 20, 1993
  112.     Added support for other hardware - ATI XL (untested)
  113.     and VESA compliant boards, (like S3 based boards with
  114.     a HiColor DAC and a (bug free!) VESA bios.
  115.  
  116. PROPOSED FUTURE ENHANCHMENTS
  117.  
  118.        I would like to hear from users of the library.  If no
  119.      one seems to be using the library, I won't release any
  120.      more versions.  I would appreciate bug reports, with
  121.      examples of failures, and suggestions for additions or
  122.      improvments to the library.  (I unfortunately cannot
  123.      promise that I will be able to reply to all enquiries or
  124.      comments, but I can promise that your comments will be
  125.      read and considered.  I can also definately NOT promise
  126.      to help with programming problems!)  Here are some ways
  127.      that I would like to improve the library:
  128.  
  129.      - I will probably make versions of the library for
  130.      Microsoft C 6.0 and Watcom 8.5. (especially if someone
  131.      pays me...)
  132.  
  133.      - I may combine this library with my SuperVGA library.
  134.  
  135.      - I would like samples of Targa(tm) files (or GIFs) which
  136.      do not display properly when loaded with the
  137.      HCTGAVIEW or HCGIFVIEW funtions.
  138.  
  139.      - Support for other graphics hardware.  Hopefully, we will
  140.      be able to support new hardware and graphics modes as they
  141.      are introduced. 
  142.  
  143.      - Faster GIF(tm) and Targa(tm) decoding and encoding
  144.  
  145.      - Faster everything else.
  146.  
  147.      - More primitives, like antialiased lines, circles and so on.
  148.  
  149.      - Small pop-up menu to work with the mouse
  150.  
  151.      - Real Documentation!
  152.  
  153.      - Support for 64k color modes.
  154.  
  155.  
  156.  
  157. FUNCTION SYNOPSES
  158.  
  159.  
  160.  - Graphics Macros/Defines
  161.  
  162.  
  163. #define HC_SVGALO    0    /* 640x350 */ /* Not all modes supported */
  164. #define HC_SVGAMED    1    /* 640x400 */ /* on all cards!!! */
  165. #define HC_SVGAHI    2    /* 640x480 */
  166. #define HC_SVGAHI2    3       /* 800x600 */
  167. #define HC_SVGAHI3    4    /* 1024x768 */
  168. #define HC_SVGAHI4    5       /* 1280x1024 */
  169.  
  170.  
  171. #define    XOR    0    /* BitBlt modes */
  172. #define OR    1
  173. #define COPY    2
  174.  
  175.  
  176. #define RGB256INT(r,g,b)    /* Make a HiColor color integer from
  177.                  Red, Green, Blue values (all in 0..255 range)*/
  178.  
  179. #define RGBINT(r,g,b)        /* Make a HiColor color integer from
  180.                  Red, Green, Blue values (all in 0..31 range)*/
  181.  
  182. #define INTRED(c)        /* Get Red component from HiColor color int */
  183. #define INTGREEN(c)             /*     Green */
  184. #define INTBLUE(c)        /*     Blue */
  185. #define INTRED256(c)        /*     Red (0..255) range */
  186. #define INTGREEN256(c)        /*     Green */
  187. #define INTBLUE256(c)              /*     Blue */
  188.  
  189.  
  190.  - Graphics Functions
  191.  
  192.  
  193. int hicolorDAC (void);
  194.  
  195.  
  196.     Check for existence of Sierra HiColor DAC hardware.
  197.  
  198.     Returns:    TRUE or FALSE
  199.  
  200.  
  201. int tseng4000 (void);
  202.  
  203.     Check for existence of TSENG 4000(tm) hardware.
  204.  
  205.     Returns:    TRUE or FALSE
  206.  
  207.  
  208. int hcsetmodetseng (int Mode);
  209.  
  210.     Set HiColor modes on TSENG 4000 HiColor hardware.  The MODE
  211.     is 0..3 and defined in HICOLOR.H  Not all modes are supported
  212.     on all cards.
  213.  
  214.     Returns:    TRUE or FALSE
  215.  
  216.  
  217. int hcmodesize(int picwidth,int picheight);
  218.  
  219.     Get a Mode number for the HCSETMODETSENG function above, given
  220.     the size of a picture that you would like to display.  This
  221.     function currently just finds the mininum screen height that will
  222.     accomadate a given picture size.
  223.  
  224.     Returns:    integer 0..3 corresponding to Mode number defined
  225.             in HICOLOR.H
  226.  
  227.  
  228. void hctextmode (void);
  229.  
  230.     Set the video to text mode (bios mode 3).
  231.  
  232.  
  233. void hcputpoint (WORD x, WORD y, WORD color);
  234.  
  235.     Put a single pixel at location (X,Y) on the HiColor mode
  236.     graphics screen.  color  is a integer 0..32767 made up
  237.     of three 5 bit numbers representing (red,green,blue).
  238.  
  239.     Use the RGBINT or RGB256INT macros to define a color
  240.     number from the red, green and blue components.
  241.     RGBINT defines a color integer given the red, green and
  242.     blue components as numbers from 0..31 (a "native" HiColor
  243.     15 bit color value.)  RGB256INT returns a color integer
  244.     given the red, green and blue components as numbers from
  245.     0..255 (a "true-color" 24bit color). INTRGB and INTRGB256
  246.     perform the reverse operation - they return the red, green
  247.     and blue color components given a 15 bit color integer.
  248.  
  249.  
  250. void hcputpointxor (WORD x, WORD y, WORD color);
  251.  
  252.     As above, except XOR the color with the existing color
  253.     at the (X,Y) location.
  254.  
  255.  
  256. void hcputpointrgb (WORD x, WORD y, WORD r, WORD g, WORD b);
  257.  
  258.     Place a single pixel, specifying location and red, green,
  259.     blue color components.
  260.  
  261.  
  262. WORD rgb265int (WORD r, WORD g, WORD b);
  263.  
  264.     Function corresponding to RGB256 macro.
  265.  
  266.     Returns:    Color integer.
  267.  
  268.  
  269. WORD rgbint (WORD r, WORD g, WORD b);
  270.  
  271.     Function corresponding to RGBINT macro.
  272.  
  273.     Returns:    Color integer
  274.  
  275.  
  276. void intrgb256 (WORD color, WORD *r, WORD *g, WORD *b);
  277.  
  278.     Function corresponding to INTRGB256.
  279.  
  280.  
  281. void intrgb (WORD color, WORD *r, WORD *g, WORD *b);
  282.  
  283.     Function corresponding to INTRGB.
  284.  
  285.  
  286. WORD hcgetpoint (WORD x, WORD y);
  287.  
  288.     Get the color value of a pixel at location (X,Y).
  289.  
  290.     Returns:    color integer, 0..32767
  291.  
  292.  
  293. void hcgetpointrgb (WORD x, WORD y, WORD *r, WORD *g, WORD *b);
  294.  
  295.     Get the red, green, blue color values of a pixel at
  296.     location (X,Y).
  297.  
  298.     Returns:    red, green, blue in range 0..31
  299.  
  300.  
  301. WORD hcgetmaxx (void);
  302.  
  303.     Return the maximum x coordinate for the current HiColor mode.
  304.  
  305. WORD hcgetmaxy (void);
  306.  
  307.     Return the minimum y coordinate for the current HiColor mode.
  308.  
  309.  
  310. void hchline (WORD x, WORD y, WORD x1, register WORD color);
  311.  
  312.     Plot a horizontal line from (X,Y) to (X1,Y) using "color."
  313.  
  314.  
  315. void hcvline (WORD x, WORD y, WORD y1, register WORD color);
  316.  
  317.     Plot a vertical line from (X,Y) to (X,Y1) using color.
  318.  
  319.  
  320. void hchlinexor (WORD x, WORD y, WORD x1, register WORD color);
  321.  
  322.     Plot a horizontal line from (X,Y) to (X1,Y), XORing
  323.     color with the existing color.
  324.  
  325.  
  326. void hcvlinexor (WORD x, WORD y, WORD y1, register WORD color);
  327.  
  328.     Plot a vertical line from (X,Y) to (X1,Y), XORing
  329.     color with the existing color.
  330.  
  331.  
  332. void hcrectangle (WORD x, WORD y, WORD x1, WORD y1, WORD color);
  333.  
  334.     Plot a rectangle from (X,Y) to (X1,Y1) using color.
  335.  
  336.  
  337. void hcrectanglexor (WORD x, WORD y, WORD x1, WORD y1, WORD color);
  338.  
  339.     Plot a rectangle from (X,Y) to (X1,Y1), XORing
  340.     color with the existing color.
  341.  
  342. void hcline(int a1, int b1, int a2, int b2, WORD lcolor);
  343.  
  344.     Plot a line from (X,Y) to (X1,Y1) in lcolor.
  345.  
  346.  
  347. void hclinexor(int a1, int b1, int a2, int b2, WORD lcolor);
  348.  
  349.     Plot a line from (X,Y) to (X1,Y1), XORing lcolor
  350.     with the existing color.
  351.  
  352.  
  353. void hccircle(WORD xc,WORD yc,WORD rad,WORD color);
  354.  
  355.     Plot a circle at (XC,YC) using radius rad and color.
  356.  
  357.  
  358. void hcfillcircle(WORD xc,WORD yc,WORD rad,WORD color);
  359.  
  360.     Plot a filled circle at (XC,YC) using radius rad and color.
  361.  
  362.  
  363. void hcbar (WORD x, WORD y, WORD x1, WORD y1, register WORD color);
  364.  
  365.     Plot a filled rectangle from (X,Y) to (X1,Y1).
  366.  
  367.  
  368. void hcclrscr (WORD color);
  369.  
  370.     Fill the entire screen with color.
  371.  
  372.  
  373. void hcputrow (WORD x, WORD y, register WORD w, register WORD *buf);
  374.  
  375.     Fill a row starting at (X,Y) of width w, using the colors
  376.     from lbuf.
  377.  
  378.  
  379. void hcputrowxor (WORD x, WORD y, register WORD w, register WORD *buf);
  380.  
  381.     Fill a row starting at (X,Y) of width w, XORing the colors
  382.     from lbuf with the existing colors.
  383.  
  384.  
  385. void hcputrowor (WORD x, WORD y, register WORD w, register WORD *buf);
  386.  
  387.     Fill a row starting at (X,Y) of width w, ORing the colors
  388.     from lbuf with the existing colors.
  389.  
  390.  
  391. void hcgetrow (WORD x, WORD y, register WORD w, register WORD *buf);
  392.  
  393.     Get a row starting at (X,Y) of width w, putting the colors
  394.     into lbuf.
  395.  
  396.  
  397. DWORD hcgetimagesize (register WORD left, register WORD top, register WORD right,register WORD bottom);
  398.  
  399.     Get the size in bytes required to "hcgetimage" an area of
  400.     the screen defined by (LEFT,TOP) to (RIGHT,BOTTOM).
  401.  
  402.     Returns:    unsigned long integer of the
  403.             size in bytes of the region.
  404.  
  405.  
  406. void hcgetimage (WORD left, WORD top, WORD right, WORD bottom, WORD *bitmap);
  407.  
  408.     Get the area of the screen from (LEFT,TOP) to (RIGHT,BOTTOM),
  409.     placing the colors into buffer bitmap.
  410.  
  411.  
  412. void hcputimage (WORD left, WORD top, WORD *bitmap, WORD drawtype);
  413.  
  414.     Put a bitmap onto the screen at position (LEFT,TOP), using
  415.     drawtype 0..2 (XOR, OR or COPY, as defined in HICOLOR.H).
  416.  
  417. void hcputchr (unsigned char ch, WORD xpos, WORD ypos, WORD fg, WORD background);
  418.  
  419.     Draw a single character ch at position (XPOS,YPOS) using foreground
  420.     color fg and background color BG.  The (XPOS,YPOS) position refers
  421.     to the top left of the character.  The characters are drawn using
  422.     the font from ROM.
  423.  
  424.  
  425. void hcputstr (char *str, WORD xpos, WORD ypos, WORD fg, WORD background);
  426.  
  427.     Draw a string onto the screen at position (XPOS,YPOS) using
  428.     foreground and background colors FG and BG.
  429.  
  430.  
  431. void hcfill(int x,int y,int ncolor);
  432.  
  433.     Flood fill a bounded area of the screen starting at (X,Y)
  434.     and using color ncolor.  All contiguous pixels that are the
  435.     same color as pixel (X,Y) will be filled with color ncolor.
  436.  
  437.  
  438. void hcpfill(int x,int y,int bordcol,WORD *pat,int pw,int ph);
  439.  
  440.     Flood fill a bounded area of the screen with a pattern
  441.     PAT, which is PW pixels wide and PH pixels high.  All
  442.     pixels not equal to bordcol will be filled with the pattern.
  443.     The pattern may be a simple array of integers, or may be
  444.     a bitmap captured from the screen, and converted using
  445.     HCIMAGETOPATTERN below.
  446.  
  447.  
  448. WORD *hcimagetopattern(WORD *bitmap,WORD *w,WORD *h);
  449.  
  450.     Convert a bitmap which was captured from the screen using
  451.     HCGETIMAGE into a pattern for use with HCPFILL.
  452.  
  453.     Returns:    WORD *pointer to a pattern, and the width
  454.             and height of the pattern.
  455.  
  456.  
  457.  - Mouse Macros/Defines
  458.  
  459.  
  460. #define GRCURSORSIZEX    11    /* Max. graphics cursor width in pixels */
  461. #define GRCURSORSIZEY    15    /* Max. cursor height in pixels + 1 */
  462. #define GRCURSORNUM    10    /* Max number of default and definable cursors */
  463.  
  464. #define ARROWCURSOR        0    /* Graphics cursor types */
  465. #define SMALLARROWCURSOR    1
  466. #define CROSSHAIR        2
  467. #define SMALLCROSSHAIR        3
  468. #define DIAGCROSSHAIR        4
  469.  
  470. typedef int    grcursortype[GRCURSORSIZEX][GRCURSORSIZEY];
  471. typedef char    mousestr[80];
  472.  
  473.  
  474.  - Mouse functions
  475.  
  476. int  initmouse(void);                /* Init. mouse driver */
  477.  
  478.     Low-level mouse initialization routine.  Checks for
  479.     mouse driver, initializes.
  480.  
  481.     Returns:    TRUE for success.
  482.  
  483.  
  484. void showmouse(void);                /* Show (text) cursor */
  485.  
  486.     Show cursor (text mode only).
  487.  
  488.  
  489. void hidemouse(void);                /* Unshow (text) cursor */
  490.  
  491.     Hide cursor (text mode only).
  492.  
  493.  
  494. void getmouse(int *x,int *y,int *buttons);/* Get position */
  495.  
  496.     Get current mouse position (X,Y) and button state (BUTTONS).
  497.  
  498.  
  499. void putmouse(int x,int y);            /* Place mouse */
  500.  
  501.     Set mouse position to (X,Y).
  502.  
  503.  
  504. void getmousebuttonon(int button,int *buttonstate,
  505.               int *numpresses,int *x,int *y);/* Get buttons pressed */
  506.  
  507.     Get mouse button press state. Returns number of presses, (X,Y)
  508.     location.
  509.  
  510.  
  511. void getmousebuttonoff(int button,int *buttonstate,
  512.                int *numreleases,int  *x,int *y);/* Get buttons released */
  513.  
  514.     Get mouse button release state. Returns number of releases, (X,Y)
  515.     location.
  516.  
  517.  
  518. void setmouserange(int x,int y,int x1,int y1);    /* Set range */
  519.  
  520.     Restrict the movement of the mouse to the rectangle defined
  521.     by (X,Y) of (X1,Y1).
  522.  
  523.  
  524. void getmousemotion(int *x,int *y);        /* Get movement */
  525.  
  526.     Return mouse movement in (X,Y).
  527.  
  528.  
  529. void setmousemove(int x,int y);            /* Set sensitivity */
  530.  
  531.     Set mouse sensitivity to (X,Y).
  532.  
  533.  
  534. void setgrcursor(int index,grcursortype newgrcursor);/* Set cursor bitmap */
  535.  
  536.     Set the type of graphics cursor to be used to index.
  537.     Predefined cursors are defined as 0..4 in HICOLOR.H.
  538.  
  539.  
  540. void putgrcursor(int x,int y);        /* Place graphics cursor */
  541.  
  542.     Put the graphics cursor at location (X,Y).
  543.  
  544.  
  545. void unputgrcursor(void);        /* Remove graphics cursor */
  546.  
  547.     Remove the previous placed graphics cursor.
  548.  
  549.  
  550. int getgrcursorx(void);                 /* Get current postn */
  551.  
  552.     Get current horizontal graphics cursor position.
  553.  
  554.     Returns:    Current X position.
  555.  
  556.  
  557. int getgrcursory(void);
  558.  
  559.     Get current vertical graphics cursor position.
  560.  
  561.     Returns:    Current Y position.
  562.  
  563.  
  564. int initgrcursor(int grcursorindex,int color);/* Init. graphics cursor */
  565.  
  566.     Initialize the graphics cursor to grcursorindex and color,
  567.     where grcursorindex is the cursor type to use.
  568.  
  569.  
  570. void closegrcursor(void);
  571.  
  572.     Remove, deinitialize the graphics cursor.
  573.  
  574.  
  575.  - TARGA(tm) Macros/Defines
  576.  
  577.  
  578. #define HCTGACANTOPEN    -1
  579. #define HCTGANOMEM    -2
  580. #define HCTGANOTSUPPORTED -3
  581. #define HCTGACANTREAD    -4
  582. #define HCTGACANTWRITE    -5
  583.  
  584. #define MAXTGAXWIDTH    1280
  585. #define MAXTCOMMENT    256
  586.  
  587. extern unsigned char tcomment[MAXTCOMMENT];
  588. extern unsigned char tcommentsize;
  589.  
  590.  
  591.  - TARGA(tm) Functions
  592.  
  593.  
  594. int hctgasize(char *fname,int *w,int *h,unsigned char *csize,unsigned char *comm);
  595.  
  596.     Get the size of a Targa(tm) file FNAME.
  597.  
  598.     Returns:    Width W and Height H, and the size
  599.             of the comment COMM, in bytes, CSIZE.
  600.  
  601.  
  602. int hctgaview(char *fname,int x,int y,int x1,int y1,int dither);
  603.  
  604.     Display the Targa(tm) file FNAME in the rectangle defined by
  605.     (X,Y) and (X1,Y1).  If DITHER is TRUE, then dither 24
  606.     or 32 bit images while displaying.
  607.  
  608.     Returns:    0 for success or an error code as
  609.             defined in HCTARGA.H
  610.  
  611.  
  612. int hctgasave(char *fname,int x,int y,int x1,int y1,int compressed,unsigned char csize,unsigned char *comm);
  613.  
  614.     Save the rectangular region of the screen defined by (X,Y)
  615.     and (X1,Y1) to a Targa-16(tm) file FNAME.  Save as a compressed
  616.     file if COMPRESSED is TRUE, use a comment of length CSIZE (up to
  617.     255 characters) from COMM.  If X is -1 then the width of the image
  618.         will be centered on the screen, and if Y is -1 then the height of
  619.         image will be centered on the screen.  If X1 is not -1 then the
  620.     entire width of the image will be displayed, and similarily for
  621.     the height (otherwise the image will be clipped to (X1,Y1).
  622.  
  623.     Returns:    0 for success or an error code as defined in
  624.             HCTARGA.H
  625.  
  626.  
  627.  
  628.  - GIF(tm) Macros/Defines
  629.  
  630.  
  631. #define HCGIFCANTOPEN    -1
  632. #define HCGIFNOMEM    -2
  633. #define HCGIFBADGIF    -3
  634. #define HCGIFNOTGIF    -4
  635.  
  636.  
  637.  - GIF(tm) Functions
  638.  
  639.  
  640. int hcgifsize(char *filename,int *width,int *height,long offset);
  641.  
  642.     Get the size of a GIF(tm) file FNAME, reading FNAME starting
  643.     at position OFFSET.
  644.  
  645.     Returns:    Width W and Height H, and the size
  646.             of the comment COMM, in bytes, CSIZE.
  647.  
  648.  
  649. int hcgifview(char *filename,int xs,int ys,long offset,int autoscale);
  650.  
  651.     Display the GIF(tm) file FNAME starting at position (XS,YS),
  652.     reading FNAME starting at position OFFSET.  If AUTOSCALE is
  653.     TRUE, then sky the image up to try to fill the available area.
  654.     If XS is -1 then the width of the image will be centered on the
  655.     screen, and if YS is -1 then the height of image will be centered
  656.     on the screen. 
  657.  
  658.     Returns:    0 for success or an error code as
  659.             defined in HCTARGA.H
  660.  
  661.